// 虚拟列表组件类型定义

import React from 'react';

// 虚拟列表项接口
export interface VirtualItem {
  index: number;
  start: number; // 项目在容器中的起始位置
  end: number;   // 项目在容器中的结束位置
  size: number;  // 项目高度
}

// 虚拟列表属性接口
export interface VirtualListProps<T> {
  // 必需属性
  items: T[];
  containerHeight: number;
  renderItem: (props: VirtualListItemProps<T>) => React.ReactElement;
  
  // 可选属性
  itemHeight?: number | ((index: number, item: T) => number);
  overscan?: number; // 预渲染额外项目数量，默认5
  className?: string;
  onScroll?: (scrollTop: number) => void;
  onVisibleRangeChange?: (startIndex: number, endIndex: number) => void;
  
  // 性能优化选项
  enableVirtualization?: boolean; // 是否启用虚拟化，默认true
  scrollThrottleMs?: number; // 滚动事件节流时间，默认16ms
}

// 虚拟列表项属性接口
export interface VirtualListItemProps<T> {
  index: number;
  item: T;
  style: React.CSSProperties;
  isVisible: boolean;
}

// 虚拟列表Hook返回值
export interface UseVirtualListReturn {
  virtualItems: VirtualItem[];
  totalSize: number;
  startIndex: number;
  endIndex: number;
  scrollToIndex: (index: number, align?: 'start' | 'center' | 'end') => void;
  scrollToOffset: (offset: number) => void;
  containerRef: React.RefObject<HTMLDivElement>;
}

// 虚拟列表状态
export interface VirtualListState {
  scrollTop: number;
  containerHeight: number;
  isScrolling: boolean;
  lastScrollTime: number;
}

// 滚动对齐方式
export type ScrollAlignment = 'start' | 'center' | 'end' | 'auto';

// 虚拟列表测量缓存
export interface SizeCache {
  [index: number]: number;
}

// 虚拟列表性能统计
export interface VirtualListMetrics {
  totalItems: number;
  renderedItems: number;
  renderRatio: number; // 渲染比例
  averageItemHeight: number;
  scrollPosition: number;
  isVirtualized: boolean;
}

// 默认配置
export const VIRTUAL_LIST_DEFAULTS = {
  ITEM_HEIGHT: 40,
  OVERSCAN: 5,
  SCROLL_THROTTLE_MS: 16,
  ENABLE_VIRTUALIZATION: true,
  MIN_ITEMS_FOR_VIRTUALIZATION: 50 // 少于此数量时不启用虚拟化
} as const;